feat(flashblocks): add UnifiedReceiptBuilder for seamless deposit receipt handling #345

Himess · 2026-01-10T21:44:55Z

Summary

Introduces UnifiedReceiptBuilder - a wrapper that handles both deposit and non-deposit transaction receipts seamlessly, eliminating the try-catch pattern required by OpReceiptBuilder.

Changes

Added receipt_builder.rs with UnifiedReceiptBuilder<C> struct
Single build() method handles both tx types internally
Simplified state_builder.rs - removed ~40 lines of manual deposit handling
Removed unused alloy-op-evm dependency

Closes #309

cb-heimdall · 2026-01-10T21:44:59Z

🟡 Heimdall Review Status

Requirement Status More Info

Reviews

🟡 0/1

Denominator calculation

Show calculation

1 if user is bot 0

1 if user is external 0

2 if repo is sensitive 0

From .codeflow.yml 1

Additional review requirements

Show calculation

Max	0

0

From CODEOWNERS 0

Global minimum 0

Max 1

1

1 if commit is unverified 0

Sum 1

refcell · 2026-01-11T21:39:18Z

crates/client/flashblocks/src/state_builder.rs

+                    input,
+                    &mut self.l1_block_info,
+                )
+                .unwrap()


Can we properly bubble up an error here instead of using .unwrap()? We should have fixed this previously but if we're modifying this, let's cleanup past issues.

refcell · 2026-01-11T21:41:42Z

crates/client/flashblocks/src/state_builder.rs

+                        self.cumulative_gas_used,
+                        self.pending_block.timestamp,
+                    )
+                    .map_err(|_| ExecutionError::DepositAccountLoad)?;


Let's implement From<ReceiptBuildError> for ExecutionError. This should let us remove the .map_err here and just use the ? operator.

So this would just become:

let receipt = self .receipt_builder .build( &mut self.evm, &transaction, result, &state, self.cumulative_gas_used, self.pending_block.timestamp, )?;

refcell · 2026-01-11T21:43:12Z

crates/client/flashblocks/src/receipt_builder.rs

+        evm: &mut E,
+        transaction: &Recovered<OpTxEnvelope>,
+        result: ExecutionResult<E::HaltReason>,
+        _state: &EvmState,


Can we remove this argument if it's unused?

crates/client/flashblocks/src/receipt_builder.rs

refcell

A few changes + nits

Himess · 2026-01-12T10:53:16Z

@refcell Ready to review

refcell · 2026-01-12T14:54:45Z

crates/client/flashblocks/src/error.rs

+impl From<crate::ReceiptBuildError> for ExecutionError {
+    fn from(_: crate::ReceiptBuildError) -> Self {
+        Self::DepositAccountLoad
+    }
+}
+


Shouldn't this be the ExecutionError::RpcReceiptBuild() error variant rather than the ExecutionError::DepositAccountLoad unless I'm not understanding something?

Yeah you are absolutly right

refcell · 2026-01-12T14:56:11Z

crates/client/flashblocks/src/receipt_builder.rs

+    #[test]
+    fn test_legacy_receipt_type() {
+        let tx = create_legacy_tx();
+        assert_eq!(tx.tx_type(), OpTxType::Legacy);
+    }
+
+    #[test]
+    fn test_deposit_receipt_type() {
+        let tx = create_deposit_tx();
+        assert_eq!(tx.tx_type(), OpTxType::Deposit);
+    }


rm

Suggested change

#[test]

fn test_legacy_receipt_type() {

let tx = create_legacy_tx();

assert_eq!(tx.tx_type(), OpTxType::Legacy);

}

#[test]

fn test_deposit_receipt_type() {

let tx = create_deposit_tx();

assert_eq!(tx.tx_type(), OpTxType::Deposit);

}

refcell · 2026-01-12T15:03:36Z

crates/client/flashblocks/src/receipt_builder.rs

+    #[test]
+    fn test_tx_type_to_receipt_mapping() {
+        let receipt =
+            Receipt { status: Eip658Value::Eip658(true), cumulative_gas_used: 21000, logs: vec![] };
+
+        // Test all non-deposit variants
+        assert!(matches!(OpReceipt::Legacy(receipt.clone()), OpReceipt::Legacy(_)));
+        assert!(matches!(OpReceipt::Eip2930(receipt.clone()), OpReceipt::Eip2930(_)));
+        assert!(matches!(OpReceipt::Eip1559(receipt.clone()), OpReceipt::Eip1559(_)));
+        assert!(matches!(OpReceipt::Eip7702(receipt), OpReceipt::Eip7702(_)));
+    }


This is also a no-op test, rm.

Suggested change

#[test]

fn test_tx_type_to_receipt_mapping() {

let receipt =

Receipt { status: Eip658Value::Eip658(true), cumulative_gas_used: 21000, logs: vec![] };

// Test all non-deposit variants

assert!(matches!(OpReceipt::Legacy(receipt.clone()), OpReceipt::Legacy(_)));

assert!(matches!(OpReceipt::Eip2930(receipt.clone()), OpReceipt::Eip2930(_)));

assert!(matches!(OpReceipt::Eip1559(receipt.clone()), OpReceipt::Eip1559(_)));

assert!(matches!(OpReceipt::Eip7702(receipt), OpReceipt::Eip7702(_)));

}

refcell · 2026-01-12T15:07:35Z

crates/client/flashblocks/src/receipt_builder.rs

+    #[test]
+    fn test_build_legacy_receipt() {
+        let chain_spec = Arc::new(OpChainSpecBuilder::base_mainnet().build());
+        let mut db = InMemoryDB::default();
+        let mut evm = create_test_evm(chain_spec.clone(), &mut db);
+
+        let builder = UnifiedReceiptBuilder::new(chain_spec);
+        let tx = create_legacy_tx();
+        let result = create_success_result();
+
+        let receipt = builder.build(&mut evm, &tx, result, 21000, 0).expect("build should succeed");
+
+        assert!(matches!(receipt, OpReceipt::Legacy(_)));
+        if let OpReceipt::Legacy(inner) = receipt {
+            assert!(inner.status.coerce_status());
+            assert_eq!(inner.cumulative_gas_used, 21000);
+        }


refcell

Much better. A couple of nits. Will add @meyer9 as a reviewer to get another pair of eyes since this addresses a ticket he wrote.

You'll also need to resolve conflicts with trunk

meyer9

LG other than the comments @refcell left! Will let them approve once comments are addressed!

…eipt handling Add a new UnifiedReceiptBuilder that handles both deposit and non-deposit transactions seamlessly without requiring error handling at the call site. The builder wraps OpRethReceiptBuilder and automatically handles the deposit receipt case internally, eliminating the need for callers to implement the try-catch pattern typically required when using build_receipt followed by build_deposit_receipt. Changes: - Add receipt_builder module with UnifiedReceiptBuilder - Update PendingStateBuilder to use UnifiedReceiptBuilder - Simplify execute_with_evm method by removing manual deposit handling - Remove receipt_builder parameter from PendingStateBuilder::new() Closes base#309

Removed wrapper around OpRethReceiptBuilder and implemented direct receipt building logic. This fixes type mismatches between OpTxEnvelope and OpTransactionSigned that prevented compilation. - Use direct OpTxType matching instead of build_receipt/build_deposit_receipt pattern - Accept ExecutionResult<E::HaltReason> for proper generic type handling - Remove unused alloy-op-evm dependency

- Add From<ReceiptBuildError> for ExecutionError and StateProcessorError - Remove unused _state parameter from build() - Replace .unwrap() with proper error handling - Add comprehensive tests for receipt building logic

- Add EVM-based tests that directly test build() method - Test legacy receipt building - Test deposit receipt building - Test Canyon hardfork activation (deposit_receipt_version) - Test failed transaction receipt

- Use RpcReceiptBuild error variant in From<ReceiptBuildError> impl - Remove no-op tests (test_legacy_receipt_type, test_deposit_receipt_type, test_tx_type_to_receipt_mapping)

Himess · 2026-01-13T14:34:30Z

@refcell I think it's ready now

Himess marked this pull request as draft January 10, 2026 21:58

Himess marked this pull request as ready for review January 10, 2026 22:53

refcell reviewed Jan 11, 2026

View reviewed changes

crates/client/flashblocks/src/receipt_builder.rs Show resolved Hide resolved

refcell requested changes Jan 11, 2026

View reviewed changes

Himess requested a review from refcell January 12, 2026 10:53

refcell reviewed Jan 12, 2026

View reviewed changes

refcell requested a review from meyer9 January 12, 2026 15:10

meyer9 reviewed Jan 12, 2026

View reviewed changes

danyalprout added this to the v0.4.0 milestone Jan 12, 2026

Himess and others added 9 commits January 13, 2026 17:09

style: apply rustfmt formatting

bdd9dc8

refactor: add const fn to simple constructors and getters

8b7d5f8

refactor: address review feedback for UnifiedReceiptBuilder

6c2993c

- Add From<ReceiptBuildError> for ExecutionError and StateProcessorError - Remove unused _state parameter from build() - Replace .unwrap() with proper error handling - Add comprehensive tests for receipt building logic

test: add build() method tests for UnifiedReceiptBuilder

fe8deb0

- Add EVM-based tests that directly test build() method - Test legacy receipt building - Test deposit receipt building - Test Canyon hardfork activation (deposit_receipt_version) - Test failed transaction receipt

refactor: address review feedback for receipt builder

b947528

- Use RpcReceiptBuild error variant in From<ReceiptBuildError> impl - Remove no-op tests (test_legacy_receipt_type, test_deposit_receipt_type, test_tx_type_to_receipt_mapping)

fix: update receipt_builder imports and tests for upstream compatibility

970d915

chore: update Cargo.lock

a24dbfe

Himess force-pushed the feat/unified-receipt-builder branch from 090c618 to a24dbfe Compare January 13, 2026 14:28

Himess requested a review from refcell January 13, 2026 18:50

feat(flashblocks): add UnifiedReceiptBuilder for seamless deposit receipt handling #345

Are you sure you want to change the base?

feat(flashblocks): add UnifiedReceiptBuilder for seamless deposit receipt handling #345

Conversation

Himess commented Jan 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Uh oh!

cb-heimdall commented Jan 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟡 Heimdall Review Status

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

refcell left a comment

Choose a reason for hiding this comment

Uh oh!

Himess commented Jan 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

refcell left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

meyer9 left a comment

Choose a reason for hiding this comment

Uh oh!

Himess commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Himess commented Jan 10, 2026 •

edited

Loading

cb-heimdall commented Jan 10, 2026 •

edited

Loading

refcell left a comment •

edited

Loading

Himess commented Jan 13, 2026 •

edited

Loading